# TOML Plugin

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-toml" />

Used to import TOML files and convert them into JavaScript objects.

:::tip
[TOML](https://toml.io/) is a semantically explicit, easy-to-read configuration file format.
:::

## Quick Start

### Install the Plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-toml -D" />

### Register Plugin

You can register the plugin in the `rsbuild.config.ts` file:

```ts title="rsbuild.config.ts"
import { pluginToml } from '@rsbuild/plugin-toml';

export default {
  plugins: [pluginToml()],
};
```

## Example

Suppose the project has the following code in `example.toml`:

```toml title="example.toml"
hello = "world"

[foo]
bar = "baz"
```

After using the TOML plugin, you can reference it as follows:

```js
import example from './example.toml';

console.log(example.hello); // 'world';
console.log(example.foo); // { bar: 'baz' };
```

## Type Declaration

When you import TOML files in TypeScript code, please create a `src/env.d.ts` file in your project and add the corresponding type declarations.

- Method 1: If the `@rsbuild/core` package is installed, you can directly reference the type declarations provided by `@rsbuild/core`:

```ts title="src/env.d.ts"
/// <reference types="@rsbuild/core/types" />
```

- Method 2: Manually add the required type declarations:

```ts title="src/env.d.ts"
declare module '*.toml' {
  const content: Record<string, any>;
  export default content;
}
```
